<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.2.&nbsp;emmarun: instrumenting Java classes
on-the-fly</title><link href="../skin/css/doc.css" rel="stylesheet" type="text/css"><meta content="DocBook XSL Stylesheets V1.66.1" name="generator"><link rel="start" href="userguide.html" title="EMMA User Guide"><link rel="up" href="ar01s02.html" title="2.&nbsp;Getting Started (command line)"><link rel="prev" href="ar01s02.html" title="2.&nbsp;Getting Started (command line)"><link rel="next" href="ar01s02s03.html" title="2.3.&nbsp;Offline mode: separating instrumentation and execution"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">2.2.&nbsp;<span><b class="command">emmarun</b></span>: instrumenting Java classes
on-the-fly</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ar01s02.html"><img src="../images/prev.gif" alt="Prev"></a>&nbsp;</td><th align="center" width="60%">2.&nbsp;Getting Started (<span class="emphasis"><em>command line</em></span>)</th><td align="right" width="20%">&nbsp;<a accesskey="n" href="ar01s02s03.html"><img src="../images/next.gif" alt="Next"></a></td></tr></table><hr></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1006B"></a>2.2.&nbsp;<span><b class="command">emmarun</b></span>: instrumenting Java classes
on-the-fly</h3></div></div></div><p>Assuming you are in the <tt class="filename">examples</tt> directory
of EMMA distribution, start by compiling the example source code:</p><pre class="screen">
&gt;mkdir out 
&gt;javac -d out -g src/*.java src/search/*.java</pre><p>You can now run the main demo driver:</p><pre class="screen">
&gt;java -cp out Main
main(): running doSearch()...
main(): done</pre><p>To run the same program with coverage data collection, just insert
<span><b class="command">emmarun</b></span> in front of your program's main class
name:</p><pre class="screen">
&gt;java emmarun -cp out Main
main(): running doSearch()...
main(): done
EMMA: writing [txt] report to [...coverage.txt] ...</pre><p>The default text coverage report is generated in the current
directory:</p><pre class="screen">
[EMMA v2.0.3611 report, generated Sun Jan 11 14:18:08 CST 2004]
-------------------------------------------------------------------------------
OVERALL COVERAGE SUMMARY:
[class, %]      [method, %]     [block, %]      [line, %]       [name]
100% (3/3)      100% (7/7)      95%  (116/122)  100% (29/29)    all classes

OVERALL STATS SUMMARY:

total packages: 2
total classes:  3
total methods:  7
total executable files: 3
total executable lines: 29

COVERAGE BREAKDOWN BY PACKAGE:

[class, %]      [method, %]     [block, %]      [line, %]       [name]
100% (2/2)      100% (4/4)      91%  (64/70)    100% (18/18)    search
100% (1/1)      100% (3/3)      100% (52/52)    100% (11/11)    default package
-------------------------------------------------------------------------------</pre><p>Code coverage has never been easier! This on-the-fly
instrumentation mode is handy for light-weight testing of
<tt class="function">main()</tt> test methods, individual classes, and small- to-
mid-size programs. <span><b class="command">emmarun</b></span> also works well with Swing
applications.

      <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Other report types</h3><p>By default, <span><b class="command">emmarun</b></span> generates a
plain-text report only. The default report's depth is <tt class="option">all</tt>
which means to show the overall coverage summary followed by breakdown by
package. You can increase the default depth to include package and source
file summaries. This and many other aspects of EMMA report generation can be
configured using command line
(<tt class="option">-D&lt;report&nbsp;property&gt;=&lt;value&gt;</tt>) or an EMMA
configuration file. See <a class="olink" href="../reference/ch03.html">Chapter3, EMMA Property Reference</a>
in the reference manual for full details on EMMA configuration. Also, all EMMA command line tools
provide usage information in response to <tt class="option">-h</tt> option.</p></div>
      </p><p><span><b class="command">emmarun</b></span> application runner uses an
instrumenting classloader to add bytecode instrumentation to Java classes as
they are being loaded by the JVM. For efficiency reasons,
<span><b class="command">emmarun</b></span> does not scan your entire classpath before it
starts running. This has the side effect of only reporting on the classes
that got loaded by the application. If your intent is to base coverage
metrics on the full set of classes in the classpath, you can use the
<tt class="option">-f</tt> option.</p><p>Although it was not the case with this tutorial's sample code,
chances are your application has third-party library dependencies and you
are not interested in their coverage metrics. There are two ways to handle
this:

<div class="itemizedlist"><ul type="disc" compact="compact"><li><p>List third-party libraries in the JVM's classpath, not
<span><b class="command">emmarun</b></span>'s <tt class="option">-cp</tt> option:</p><pre class="screen">
&gt;java -cp ...somelib.jar emmarun -cp out Main</pre></li><li><p>Use a coverage filter to make sure that only the classes
of interest are instrumented:</p><pre class="screen">
&gt;java emmarun -cp out;...somelib.jar -ix +Main,+search.*  Main</pre></li></ul></div> If these techniques are not sufficient (e.g., you need to
exclude testcases from coverage and they are in the same Java packages as
the application code and do not follow a sensible naming pattern), you can
always switch to offline instrumentation as described next.</p><p><b>Further reading.&nbsp;</b>This has been a quick intro to EMMA's on-the-fly command line
instrumentation mode. For further details see <a class="olink" href="../reference/ch02s02.html">Section2, &lt;emmajava&gt;/emmarun</a> in the reference manual.</p></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ar01s02.html"><img src="../images/prev.gif" alt="Prev"></a>&nbsp;</td><td align="center" width="20%"><a accesskey="u" href="ar01s02.html"><img src="../images/up.gif" alt="Up"></a></td><td align="right" width="40%">&nbsp;<a accesskey="n" href="ar01s02s03.html"><img src="../images/next.gif" alt="Next"></a></td></tr><tr><td valign="top" align="left" width="40%">2.&nbsp;Getting Started (<span class="emphasis"><em>command line</em></span>)&nbsp;</td><td align="center" width="20%"><a accesskey="h" href="userguide.html"><img src="../images/home.gif" alt="Home"></a></td><td valign="top" align="right" width="40%">&nbsp;2.3.&nbsp;Offline mode: separating instrumentation and execution</td></tr></table></div></body></html>